Summary

Restructures the gh-cli skill to use progressive disclosure: a short router SKILL.md + 11 focused reference/*.md files, each scoped to one command group. The router tells the agent which reference file to open based on the task; individual references are loaded only when needed.

Motivation

The current skills/gh-cli/SKILL.md is a single file — 2,187 lines / 6,137 words / ~40KB — that loads in full whenever the skill activates, even for a task that only needs gh pr merge or gh api. For a reference-style skill covering 20+ command groups, this is a large context tax on every activation.

Splitting reduces the up-front load when the skill fires to ~60 lines / 530 words (~91% smaller) while preserving every command group from the original.

Layout

skills/gh-cli/
├── SKILL.md                  router + index (~60 lines)
└── reference/
    ├── auth.md               install, login, tokens, env
    ├── repo.md               gh repo
    ├── issue.md              gh issue
    ├── pr.md                 gh pr
    ├── actions.md            run / workflow / cache / secret / variable
    ├── api.md                REST, GraphQL, pagination, jq
    ├── projects.md           Projects v2
    ├── release.md            releases + assets
    ├── formatting.md         --json / --jq / --template
    ├── workflows.md          end-to-end recipes
    └── misc.md               browse, gist, codespace, org, search,
                              label, ssh-key, gpg-key, status, config,
                              extension, alias, ruleset, attestation,
                              completion, preview, agent-task

Why progressive disclosure

Anthropic's skill authoring guidance (agentskills.io) recommends keeping SKILL.md small and offloading heavy reference material to separate files that the agent reads on demand. For reference skills that span many subcommands, this keeps the "when to use + routing" signal high and the per-activation token cost low.

Minor corrections folded in

While restructuring I corrected a few command signatures that were wrong in the original:

• gh repo autolink create (was documented as add)
• gh attestation verify argument format
• gh api -f / -F field-type semantics (string coercion vs. raw)

Validation

• npm run skill:validate — all 341 skills valid ✅
• npm run build — regenerates docs/README.skills.md (the description column now reflects the new "Use when…" phrasing, and the Assets column shows reference) ✅

Description field change

The description: in frontmatter changes from:

GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line.

to:

Use when running GitHub CLI (gh) commands — auth, repos, issues, PRs, Actions/workflows, releases, projects, gists, codespaces, rulesets, or any gh api REST/GraphQL call from the command line.

The new phrasing starts with "Use when…" (matching Anthropic's CSO guidance for skill descriptions), and the coverage list is equivalent.

Test plan

• npm run skill:validate passes
• npm run build produces only expected diffs (one row in docs/README.skills.md for gh-cli)
• All 11 reference/*.md files render correctly on GitHub
• Router cross-links resolve (relative paths reference/<file>.md)
• Manual check by a reviewer: pick a task (e.g. "download the artifacts from the last failed CI run") and confirm the router points to the right file(s) (reference/actions.md)